TypeScript Compiler API: Mestring av AST-manipulering og kode transformasjon

TypeScript Compiler API tilbyr et kraftig grensesnitt for analyse, manipulering og generering av TypeScript- og JavaScript-kode. Kjernen i dette er det abstrakte syntakstreet (AST), en strukturert representasjon av kildekoden din. Å forstå hvordan man arbeider med AST åpner for muligheter til å bygge avanserte verktøy, som linters, kodeformaterere, statiske analysatorer og tilpassede kodegeneratorer.

Hva er TypeScript Compiler API?

TypeScript Compiler API er et sett med TypeScript-grensesnitt og funksjoner som eksponerer TypeScript-kompilatorens indre virkemåte. Den lar utviklere programmatisk samhandle med kompileringsprosessen, utover å bare kompilere kode. Du kan bruke den til å:

• Analysere Kode: Inspisere kodestruktur, identifisere potensielle problemer og trekke ut semantisk informasjon.
• Transformere Kode: Endre eksisterende kode, legge til nye funksjoner eller refaktorere kode automatisk.
• Generere Kode: Opprette ny kode fra bunnen av basert på maler eller annen input.

Denne API-en er avgjørende for å bygge sofistikerte utviklingsverktøy som forbedrer kodekvaliteten, automatiserer repeterende oppgaver og øker utviklerproduktiviteten.

Forståelse av det abstrakte syntakstreet (AST)

AST er en trelignende representasjon av kodens struktur. Hver node i treet representerer en syntaktisk konstruksjon, for eksempel en variabeldeklarasjon, et funksjonskall eller en kontrollflytsetning. TypeScript Compiler API tilbyr verktøy for å traversere AST, inspisere nodene og endre dem.

Vurder denne enkle TypeScript-koden:

function greet(name: string): string {
  return `Hello, ${name}!`;
}

console.log(greet("World"));

AST-en for denne koden vil representere funksjonsdeklarasjonen, retursetningen, template literalet, console.log-kallet og andre elementer i koden. Å visualisere AST kan være utfordrende, men verktøy som AST explorer (astexplorer.net) kan hjelpe. Disse verktøyene lar deg skrive inn kode og se dens tilsvarende AST i et brukervennlig format. Bruk av AST Explorer vil hjelpe deg å forstå den typen kodestruktur du vil manipulere.

Viktige AST-nodetyper

TypeScript Compiler API definerer ulike AST-nodetyper, som hver representerer en annen syntaktisk konstruksjon. Her er noen vanlige nodetyper:

• SourceFile: Representerer en hel TypeScript-fil.
• FunctionDeclaration: Representerer en funksjonsdefinisjon.
• VariableDeclaration: Representerer en variabeldeklarasjon.
• Identifier: Representerer en identifikator (f.eks. variabelnavn, funksjonsnavn).
• StringLiteral: Representerer en strengliteral.
• CallExpression: Representerer et funksjonskall.
• ReturnStatement: Representerer en retursetning.

Hver nodetype har egenskaper som gir informasjon om det tilsvarende kodeelementet. For eksempel kan en `FunctionDeclaration`-node ha egenskaper for navn, parametere, returtype og brødtekst.

Komme i gang med Compiler API

For å begynne å bruke Compiler API, må du installere TypeScript og ha en grunnleggende forståelse av TypeScript-syntaks. Her er et enkelt eksempel som demonstrerer hvordan du leser en TypeScript-fil og skriver ut dens AST:

import * as ts from "typescript";
import * as fs from "fs";

const fileName = "example.ts";
const sourceCode = fs.readFileSync(fileName, "utf8");

const sourceFile = ts.createSourceFile(
  fileName,
  sourceCode,
  ts.ScriptTarget.ES2015, // Target ECMAScript version
  true // SetParentNodes: true to retain parent references in the AST
);

function printAST(node: ts.Node, indent = 0) {
  const indentStr = "  ".repeat(indent);
  console.log(`${indentStr}${ts.SyntaxKind[node.kind]}`);

  node.forEachChild(child => printAST(child, indent + 1));
}

printAST(sourceFile);

Forklaring:

1. Importer Moduler: Importerer `typescript`-modulen og `fs`-modulen for filsystemoperasjoner.
2. Les Kildefil: Leser innholdet i en TypeScript-fil kalt `example.ts`. Du må opprette en `example.ts`-fil for at dette skal fungere.
3. Opprett SourceFile: Oppretter et `SourceFile`-objekt, som representerer roten av AST. Funksjonen `ts.createSourceFile` parser kildekoden og genererer AST.
4. Skriv ut AST: Definerer en rekursiv funksjon `printAST` som traverserer AST og skriver ut typen for hver node.
5. Kall printAST: Kaller `printAST` for å starte utskriften av AST fra rot-noden `SourceFile`.

For å kjøre denne koden, lagre den som en `.ts`-fil (f.eks. `ast-example.ts`), opprett en `example.ts`-fil med litt TypeScript-kode, og kompiler og kjør deretter koden:

tsc ast-example.ts
node ast-example.js

Dette vil skrive ut AST-en til din `example.ts`-fil til konsollen. Utdataene vil vise hierarkiet av noder og deres typer. For eksempel kan det vise `FunctionDeclaration`, `Identifier`, `Block` og andre nodetyper.

Traversering av AST

Compiler API tilbyr flere måter å traversere AST på. Den enkleste er å bruke `forEachChild`-metoden, som vist i forrige eksempel. Denne metoden besøker hver barnenode av en gitt node.

For mer komplekse traverseringsscenarier kan du bruke et `Visitor`-mønster. En visitor er et objekt som definerer metoder som skal kalles for spesifikke nodetyper. Dette lar deg tilpasse traverseringsprosessen og utføre handlinger basert på nodetypen.

import * as ts from "typescript";
import * as fs from "fs";

const fileName = "example.ts";
const sourceCode = fs.readFileSync(fileName, "utf8");

const sourceFile = ts.createSourceFile(
  fileName,
  sourceCode,
  ts.ScriptTarget.ES2015,
  true
);

class IdentifierVisitor {
  visit(node: ts.Node) {
    if (ts.isIdentifier(node)) {
      console.log(`Found identifier: ${node.text}`);
    }

    ts.forEachChild(node, n => this.visit(n));
  }
}

const visitor = new IdentifierVisitor();
visitor.visit(sourceFile);

Forklaring:

1. IdentifierVisitor-klasse: Definerer en klasse `IdentifierVisitor` med en `visit`-metode.
2. Visit-metode: `visit`-metoden sjekker om den nåværende noden er en `Identifier`. Hvis den er det, skriver den ut identifikatoren sin tekst. Den kaller deretter rekursivt `ts.forEachChild` for å besøke barnenodene.
3. Opprett Visitor: Oppretter en instans av `IdentifierVisitor`.
4. Start Traversering: Kaller `visit`-metoden på `SourceFile` for å starte traverseringen.

Dette eksemplet demonstrerer hvordan man finner alle identifikatorer i AST. Du kan tilpasse dette mønsteret for å finne andre nodetyper og utføre forskjellige handlinger.

Transformering av AST

Den virkelige kraften i Compiler API ligger i dens evne til å transformere AST. Du kan endre AST for å endre strukturen og oppførselen til koden din. Dette er grunnlaget for kode-refaktoriseringsverktøy, kodegeneratorer og andre avanserte verktøy.

For å transformere AST, må du bruke `ts.transform`-funksjonen. Denne funksjonen tar en `SourceFile` og en liste over `TransformerFactory`-funksjoner. En `TransformerFactory` er en funksjon som tar en `TransformationContext` og returnerer en `Transformer`-funksjon. `Transformer`-funksjonen er ansvarlig for å besøke og transformere noder i AST.

Her er et enkelt eksempel som demonstrerer hvordan du legger til en kommentar i begynnelsen av en TypeScript-fil:

import * as ts from "typescript";
import * as fs from "fs";

const fileName = "example.ts";
const sourceCode = fs.readFileSync(fileName, "utf8");

const sourceFile = ts.createSourceFile(
  fileName,
  sourceCode,
  ts.ScriptTarget.ES2015,
  true
);

const transformerFactory: ts.TransformerFactory = context => {
  return transformer => {
    return node => {
      if (ts.isSourceFile(node)) {
        // Create a leading comment
        const comment = ts.addSyntheticLeadingComment(
          node,
          ts.SyntaxKind.MultiLineCommentTrivia,
          " This file was automatically transformed ",
          true // hasTrailingNewLine
        );

        return node;
      }

      return node;
    };
  };
};

const { transformed } = ts.transform(sourceFile, [transformerFactory]);

const printer = ts.createPrinter({
  newLine: ts.NewLineKind.LineFeed
});

const result = printer.printFile(transformed[0]);

fs.writeFileSync("example.transformed.ts", result);

Forklaring:

1. TransformerFactory: Definerer en `TransformerFactory`-funksjon som returnerer en `Transformer`-funksjon.
2. Transformer: `Transformer`-funksjonen sjekker om den nåværende noden er en `SourceFile`. Hvis den er det, legger den til en innledende kommentar til noden ved hjelp av `ts.addSyntheticLeadingComment`.
3. ts.transform: Kaller `ts.transform` for å anvende transformasjonen på `SourceFile`.
4. Printer: Oppretter et `Printer`-objekt for å generere kode fra den transformerte AST.
5. Skriv ut og skrive: Skriver ut den transformerte koden og skriver den til en ny fil kalt `example.transformed.ts`.

Dette eksemplet demonstrerer en enkel transformasjon, men du kan bruke det samme mønsteret til å utføre mer komplekse transformasjoner, for eksempel refaktorering av kode, tillegg av loggingssetninger eller generering av dokumentasjon.

Avanserte transformasjonsteknikker

• Opprette nye noder: Bruk `ts.createXXX`-funksjonene for å opprette nye AST-noder. For eksempel oppretter `ts.createVariableDeclaration` en ny variabeldeklarasjonsnode.
• Erstatte noder: Erstatt eksisterende noder med nye noder ved hjelp av `ts.visitEachChild`-funksjonen.
• Legge til noder: Legg til nye noder i AST ved hjelp av `ts.updateXXX`-funksjonene. For eksempel oppdaterer `ts.updateBlock` en blokksetning med nye setninger.
• Fjerne noder: Fjern noder fra AST ved å returnere `undefined` fra transformasjonsfunksjonen.

Kodegenerering

Etter å ha transformert AST, må du generere kode fra den. Compiler API tilbyr et `Printer`-objekt for dette formålet. `Printer`-en tar en AST og genererer en strengrepresentasjon av koden.

Funksjonen `ts.createPrinter` oppretter et `Printer`-objekt. Du kan konfigurere printeren med forskjellige alternativer, for eksempel hvilket newline-tegn som skal brukes og om kommentarer skal inkluderes.

Metoden `printer.printFile` tar en `SourceFile` og returnerer en strengrepresentasjon av koden. Du kan deretter skrive denne strengen til en fil.

Praktiske anvendelser av Compiler API

TypeScript Compiler API har mange praktiske anvendelser innen programvareutvikling. Her er noen eksempler:

• Linters: Bygg tilpassede linters for å håndheve kodestandarder og identifisere potensielle problemer i koden din.
• Kodeformaterere: Opprett kodeformaterere for automatisk å formatere koden din i henhold til en spesifikk stilguide.
• Statiske analysatorer: Utvikle statiske analysatorer for å oppdage feil, sikkerhetssårbarheter og ytelsesflaskehalser i koden din.
• Kodegeneratorer: Generer kode fra maler eller annen input, automatiser repeterende oppgaver og reduser boilerplate-kode. For eksempel, generering av API-klienter eller databaseskjemaer fra en beskrivelsesfil.
• Refaktoriseringsverktøy: Bygg refaktoriseringsverktøy for automatisk å gi nytt navn til variabler, trekke ut funksjoner eller flytte kode mellom filer.
• Automatisering av internasjonalisering (i18n): Trekk automatisk ut oversettbare strenger fra TypeScript-koden din og generer lokaliseringsfiler for forskjellige språk. For eksempel kan et verktøy skanne kode etter strenger som sendes til en `translate()`-funksjon og automatisk legge dem til en oversettelsesressursfil.

Eksempel: Bygge en enkel Linter

La oss lage en enkel linter som sjekker for ubrukte variabler i TypeScript-kode. Denne linteren vil identifisere variabler som er deklarert, men aldri brukt.

import * as ts from "typescript";
import * as fs from "fs";

const fileName = "example.ts";
const sourceCode = fs.readFileSync(fileName, "utf8");

const sourceFile = ts.createSourceFile(
  fileName,
  sourceCode,
  ts.ScriptTarget.ES2015,
  true
);

function findUnusedVariables(sourceFile: ts.SourceFile) {
  const usedVariables = new Set();

  function visit(node: ts.Node) {
    if (ts.isIdentifier(node)) {
      usedVariables.add(node.text);
    }

    ts.forEachChild(node, visit);
  }

  visit(sourceFile);

  const unusedVariables: string[] = [];

  function checkVariableDeclaration(node: ts.Node) {
    if (ts.isVariableDeclaration(node) && node.name && ts.isIdentifier(node.name)) {
      const variableName = node.name.text;
      if (!usedVariables.has(variableName)) {
        unusedVariables.push(variableName);
      }
    }

    ts.forEachChild(node, checkVariableDeclaration);
  }

  checkVariableDeclaration(sourceFile);

  return unusedVariables;
}

const unusedVariables = findUnusedVariables(sourceFile);

if (unusedVariables.length > 0) {
  console.log("Unused variables:");
  unusedVariables.forEach(variable => console.log(`- ${variable}`));
} else {
  console.log("No unused variables found.");
}

Forklaring:

1. findUnusedVariables-funksjon: Definerer en funksjon `findUnusedVariables` som tar en `SourceFile` som input.
2. usedVariables Set: Oppretter et `Set` for å lagre navnene på brukte variabler.
3. visit-funksjon: Definerer en rekursiv funksjon `visit` som traverserer AST og legger til navnene på alle identifikatorer i `usedVariables`-settet.
4. checkVariableDeclaration-funksjon: Definerer en rekursiv funksjon `checkVariableDeclaration` som sjekker om en variabeldeklarasjon er ubrukt. Hvis den er det, legger den variabelnavnet til `unusedVariables`-arrayet.
5. Returner unusedVariables: Returnerer et array som inneholder navnene på alle ubrukte variabler.
6. Utdata: Skriver ut de ubrukte variablene til konsollen.

Dette eksemplet demonstrerer en enkel linter. Du kan utvide den til å sjekke for andre kodestandarder og identifisere andre potensielle problemer i koden din. For eksempel kan du sjekke for ubrukte importer, altfor komplekse funksjoner eller potensielle sikkerhetssårbarheter. Nøkkelen er å forstå hvordan du traverserer AST og identifiserer de spesifikke nodetypene du er interessert i.

Beste praksiser og hensyn

• Forstå AST: Invester tid i å forstå strukturen til AST. Bruk verktøy som AST explorer for å visualisere AST-en til koden din.
• Bruk Type Guards: Bruk type guards (`ts.isXXX`) for å sikre at du arbeider med riktige nodetyper.
• Vurder Ytelse: AST-transformasjoner kan være beregningsmessig kostbare. Optimaliser koden din for å minimere antall noder du besøker og transformerer.
• Håndter Feil: Håndter feil elegant. Compiler API kan kaste unntak hvis du prøver å utføre ugyldige operasjoner på AST.
• Test Grundig: Test transformasjonene dine grundig for å sikre at de produserer de ønskede resultatene og ikke introduserer nye feil.
• Bruk eksisterende biblioteker: Vurder å bruke eksisterende biblioteker som tilbyr høyere abstraksjoner over Compiler API. Disse bibliotekene kan forenkle vanlige oppgaver og redusere mengden kode du trenger å skrive. Eksempler inkluderer `ts-morph` og `typescript-eslint`.

Konklusjon

TypeScript Compiler API er et kraftig verktøy for å bygge avanserte utviklingsverktøy. Ved å forstå hvordan man arbeider med AST, kan du lage linters, kodeformaterere, statiske analysatorer og andre verktøy som forbedrer kodekvaliteten, automatiserer repeterende oppgaver og øker utviklerproduktiviteten. Selv om API-et kan være komplekst, er fordelene ved å mestre det betydelige. Denne omfattende guiden gir et grunnlag for å utforske og utnytte Compiler API effektivt i prosjektene dine. Husk å utnytte verktøy som AST Explorer, håndtere nodetyper forsiktig, og teste transformasjonene dine grundig. Med praksis og engasjement kan du låse opp det fulle potensialet til TypeScript Compiler API og bygge innovative løsninger for programvareutviklingslandskapet.

Videre utforskning:

• TypeScript Compiler API Dokumentasjon: [https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API)
• AST Explorer: [https://astexplorer.net/](https://astexplorer.net/)
• ts-morph bibliotek: [https://ts-morph.com/](https://ts-morph.com/)
• typescript-eslint: [https://typescript-eslint.io/](https://typescript-eslint.io/)